<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Appendix &mdash; Apsis v5.0.0 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '5.0.0',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Apsis v5.0.0 documentation" href="index.html" />
    <link rel="prev" title="License" href="license.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="license.html" title="License"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Apsis v5.0.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="appendix">
<h1>Appendix<a class="headerlink" href="#appendix" title="Permalink to this headline">¶</a></h1>
<p>This was cribbed from the nicred documentation which also uses superalign.</p>
<div class="section" id="superalign">
<span id="id1"></span><h2><tt class="docutils literal"><span class="pre">superalign</span></tt><a class="headerlink" href="#superalign" title="Permalink to this headline">¶</a></h2>
<div class="section" id="algorithm">
<h3>Algorithm<a class="headerlink" href="#algorithm" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">superalign</span></tt> operates in a very tree-like fashion:</p>
<ol class="arabic simple">
<li>First, the program groups the exposures in terms of those that substantially overlap (&#8216;GroupExpoures&#8217;).</li>
<li>Then, group by group (pointing by pointing), it attempts to iteratively align all the exposures
(<tt class="docutils literal"><span class="pre">AlignEntirePointing</span></tt>).  As it successfully finds alignments that work between exposures within a
group, it generates a stacked star list &#8211; where CRs are eliminated and contains an ever increasing
number of pointlike objects (individual exposures often contain more contamination and miss real objects).</li>
<li>After generating a best-effort stack of all the stars from each group, it begins to build up a
mosaic by starting at the central group and iteratively accreting nearby groups (to produce an ever
larger list of stars).  As each group is accreted, the relative position/rotation of all the groups
added to that point (within the ever growing mosaic) is  reoptimized to minimize the overall error.</li>
</ol>
<p><tt class="docutils literal"><span class="pre">superalign</span></tt> uses a variant on the similar triangle method to
determine the alignment between two individual catalogs (see
<tt class="docutils literal"><span class="pre">TryAlignment</span></tt> routine in simplealign.c).  However, instead of
attempting to find similar triangles in both images, <tt class="docutils literal"><span class="pre">superalign</span></tt>
attempts to find similar bi-directional vectors (object pairs with the
same separation and the same relative orientation).  After finding
similar vectors, <tt class="docutils literal"><span class="pre">superalign</span></tt> uses these vectors to determine a
transformation from one catalog to the other.  Each transformation is
given a score based upon how well it maps objects onto each other.
The transformation with the highest score is then adopted.  One final
set of iterations (see <tt class="docutils literal"><span class="pre">FindSolution</span></tt> routine in simplealign.c) is
then attempted (starting with the transformation which had the highest
score) to try to further improve the score.</p>
</div>
<div class="section" id="operation">
<h3>Operation<a class="headerlink" href="#operation" title="Permalink to this headline">¶</a></h3>
<p>After compiling with a &#8220;make superalign&#8221; command, <tt class="docutils literal"><span class="pre">superalign</span></tt>
is currently invoked from the command line as follows:</p>
<div class="highlight-python"><pre>superalign INPUT_SHIFTS OUTPUT_STARLIST OUTPUT_SHIFTS</pre>
</div>
<p>The first file is the INPUT_SHIFTS file and should have the following format:</p>
<div class="highlight-python"><pre>[# of exposures]
[exposure #1]  [x-shift guess #1] [y-shift guess #1] [rot-angle guess #1]
[exposure #2]  [x-shift guess #2] [y-shift guess #2] [rot-angle guess #2]
[exposure #3]  [x-shift guess #3] [y-shift guess #3] [rot-angle guess #3]
....</pre>
</div>
<p>The first exposure in the INPUT_SHIFTS file gives the reference image,
and will define the final coordinate system.  It will have an x,y
shift equal to 0,0 and a rotation angle equal to 0.</p>
<p>The second file is the OUTPUT_STARLIST file and contains a compilation
of all the objects in the final mosaic on a common grid.  Following
the construction of this object list, it should be trivial to perform
alignments onto the common frame.  The format for the file is as follows:</p>
<div class="highlight-python"><pre>1 [x position #1] [y position #1] [magnitude #1]
2 [x position #2] [y position #2] [magnitude #2]
3 [x position #3] [y position #3] [magnitude #3]
.....</pre>
</div>
<p>The third file is the OUTPUT_SHIFTS file and a list of all the determined
shifts:</p>
<div class="highlight-python"><pre>[exposure #1]  [x-shift #1] [y-shift #1] [rot-angle #1]
[exposure #2]  [x-shift #2] [y-shift #2] [rot-angle #2]
[exposure #3]  [x-shift #3] [y-shift #3] [rot-angle #3]
....</pre>
</div>
<p>For each input catalog, <tt class="docutils literal"><span class="pre">superalign</span></tt> will output a cleaned catalog.
The cleaned catalog (with the same file name as the input catalog
except with &#8220;.name&#8221; appended) will contain those objects <tt class="docutils literal"><span class="pre">superalign</span></tt>
believes are real (from the stacking analysis it does at each
position).</p>
</div>
<div class="section" id="examples">
<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
<p>To demonstrate the usage of this package, an example has been provided
in the &#8220;examples&#8221; directory.  This directory contains a list of
(distortion free) catalogs.  Each catalog is contained in a &#8220;.matchin&#8221;
file and corresponds to a single ACS exposure which will contribute to
some final set of drizzled images.</p>
<p>For this example, the usage is:</p>
<div class="highlight-python"><pre>superalign supermatch.in supermatch.stars supermatch.out</pre>
</div>
<p>&#8220;supermatch.stars&#8221; will contain the final object list for the mosaic on
the common grid.</p>
<p>&#8220;supermatch.out&#8221; will contain the derived shifts and rotations for all
of the individual exposures.</p>
</div>
<div class="section" id="free-parameters">
<h3>Free Parameters<a class="headerlink" href="#free-parameters" title="Permalink to this headline">¶</a></h3>
<p>To improve performance, one can change the following parameters which
are part of the <tt class="docutils literal"><span class="pre">SuperAlignParmRec</span></tt> structure (change with caution!):</p>
<div class="highlight-python"><pre>float TypDist;      /* Typical RMS error for objects which are well aligned */
float MaxDist;      /* MaxDist is equal to the distance two objects can be apart to even register as matches. Even if objects register as matches -- this does not imply they will have a huge effect on the final score. */
float TolPair;      /* Objects with Neighbors Closer than TolPair pixels are thrown out (due to possible deblending problems) */
float MaxShiftErr;  /* Maximum Pixel Error in X/Y Shifts */
float MaxRotErr;    /* Maximum Error in Rotation Angle (Degrees) */
float GroupSize;    /* Maximum Distance allowed between two pointings to be considered part of the same grouping */</pre>
</div>
</div>
<div class="section" id="x-and-y-distance-units">
<h3>X and Y (Distance) Units<a class="headerlink" href="#x-and-y-distance-units" title="Permalink to this headline">¶</a></h3>
<p>Arbitrary units can be used for the x/y positions and distances
throughout, but they must be consistent.  Among the shifts, x/y
positions which should be consistent are:</p>
<blockquote>
<ul>
<li><p class="first">X/Y positions of objects in the catalogs (for the individual exposures)</p>
</li>
<li><p class="first">Best guess x/y shifts given for each exposure in INPUT_SHIFTS file</p>
</li>
<li><dl class="first docutils">
<dt>The Five Following Parameters from SuperAlignParmProp (at the end of superalign.c):</dt>
<dd><ul class="first last simple">
<li>TypDist</li>
<li>MaxDist</li>
<li>TolPair</li>
<li>MaxShiftErr</li>
<li>GroupSize</li>
</ul>
</dd>
</dl>
</li>
</ul>
</blockquote>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference external" href="">Appendix</a><ul>
<li><a class="reference external" href="#superalign"><tt class="docutils literal"><span class="pre">superalign</span></tt></a><ul>
<li><a class="reference external" href="#algorithm">Algorithm</a></li>
<li><a class="reference external" href="#operation">Operation</a></li>
<li><a class="reference external" href="#examples">Examples</a></li>
<li><a class="reference external" href="#free-parameters">Free Parameters</a></li>
<li><a class="reference external" href="#x-and-y-distance-units">X and Y (Distance) Units</a></li>
</ul>
</li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="license.html"
                                  title="previous chapter">License</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/appendix.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="license.html" title="License"
             >previous</a> |</li>
        <li><a href="index.html">Apsis v5.0.0 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2009, Ken Anderson, John Blakeslee, Rychard Bouwens, Dan Magee.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
    </div>
  </body>
</html>